GOES Photo Tagger, web edition
==============================

ONE FILE. NOTHING TO INSTALL.

Double click "GOES Photo Tagger.html". It opens in your web browser and works
straight away, on Windows, on a Mac, on Linux, and on a tablet. There is no
program to install, no Python, no security warning to get past, and no
Windows .exe to build.

It also works with no internet at all, which matters mid-ocean. Everything
the page needs is inside that single file.

NOTHING LEAVES THE COMPUTER. The photographs are read, tagged and saved by
the page itself. Nothing is uploaded anywhere.


HOW A VOLUNTEER USES IT
-----------------------

1. Press "Add photographs" and choose the microscope images for ONE water
   sample. Up to five may be loaded, and they all receive the same details.

   PLEASE USE JPG IMAGES. Set the microscope software to save as JPG or
   JPEG. Other formats are accepted, but JPG is the format the survey
   expects and the one that carries the details most reliably.

   PHOTOGRAPHING THROUGH THIS PAGE INSTEAD. The page can take the pictures
   itself, straight from the USB microscope, so no separate microscope
   program is needed and no files have to be found afterwards. Fill in the
   details first, then press "Use the microscope". Close any other program
   holding the microscope before you start, such as the viewer supplied with
   it, because only one program at a time can hold a camera.

   The picture fills the screen. The camera is opened at the largest size it
   offers without scaling, whatever camera is plugged in, so a better one
   fitted later is used at its own full size. On the Plugable microscope that
   is 2592 by 1944, exactly the size of the survey archive.

   Only the disc is kept. A white circle marks the filter disc and the square
   around that circle is saved, because the rest of the frame holds nothing
   and the smaller picture makes a much smaller file. At the standard setting
   of 75 the saved square is 1458 pixels, which is 5.0 millimetres across on
   this microscope. Move the slider marked Disc if the circle is the wrong
   size for your setup.

   The figure marked Focus rises as the picture sharpens, so turn the focus
   wheel until the number stops rising. Press "Take photograph" once for each
   frame, moving the slide between frames. The space bar takes a frame and
   the escape key closes the screen. "Remove the last one" throws away a
   frame you are not happy with.

2. Fill in every box.

   IMPORTANT. The position, date and time are those of the MOMENT THE WATER
   WAS COLLECTED, not of the moment the photographs were taken. A sample
   drawn at 09:40 and photographed at 13:40 is entered as 09:40. Nothing is
   filled in from the computer clock, so these must be copied from the log
   or the plotter every time.

   Latitude and longitude may be typed in any of these forms:

        12.3456 N          12 20.736 N          12 20 44.16 N
        -12.3456           N 12.3456            12 20.736' N

   The time is the LOCAL clock time where the sample was drawn. Nothing is
   recorded in UTC. The page works out whether the sun was up from the
   position, the date and that local time.

3. Day or night is worked out from the position and the sample time, using
   the altitude of the sun, and is shown under the buttons. Change it by
   hand if the sample was taken at dusk or in deep shade.

BLANK CHECKS, EVERY 20 SAMPLES
------------------------------

Now and then, run the filter and the microscope exactly as usual, but with
WATER FILTERED BELOW 20 MICRONS, such as reverse osmosis, ultra filtered or
ceramic filtered water, and tick "This sample is a blank" in Step 2. Those
photographs show only what the equipment, the handling and the air put on the
filter, which is the measurement that tells you how much of a real sample is
contamination.
Without blanks the fibre counts cannot be separated from the boat and the
crew, and that is the first thing a reviewer asks about.

A blank is suggested every 20 samples or every 100 photographs, whichever
comes first. The page counts for you, tells you at the top of Step 2 how many
samples and photographs have passed, and turns the box amber when one is due.

It is ONLY a reminder. Nothing is blocked, and a volunteer who never runs one
can still save every sample.

When the box is ticked:

  * the water type is set to "Blank, filtered water below 20 microns" and
    the drop-down is switched off, because a blank carries no sample water
  * the files are named with BLANK in them, for example
    20260122-0940_Howard-Dryden_BLANK_1.jpg
  * samples.csv records sample_type as "blank" instead of "sample"
  * the photograph's own description begins "BLANK, filtered water below 20 microns"
  * the counter goes back to zero

The count is read out of samples.csv when you choose a folder, so it survives
closing the page and carries on where the log left off.

4. Press "Save the photographs".

The bar along the bottom is red while anything is missing and names the next
thing to fix. It turns green when the sample is ready, and only then does the
Save button come alive. Nothing can be saved until every box holds a value
the page can read.


WHERE THE FILES GO
------------------

In Chrome or Edge, press "Choose folder" first and pick where the samples
should live. The photographs are written straight into that folder and one
running samples.csv is kept there, gathering every sample. This is the better
way, and it is worth telling volunteers to use Chrome or Edge for it.

In Safari or Firefox, or if no folder is chosen, pressing Save produces a zip
file in the Downloads folder instead. Each zip holds that sample's
photographs and its own samples.csv.

Either way the files are named by sample date, time and provider:

    20260122-0940_Howard-Dryden_1.jpg
    20260122-0940_Howard-Dryden_2.jpg
    ...
    samples.csv

WHICH PICTURE FORMATS CARRY THE GEOTAG
--------------------------------------

  JPEG  (.jpg .jpeg)   tagged, EXIF written straight into the file
  PNG   (.png)         tagged, written as an eXIf chunk plus XMP, which is
                       the same arrangement the existing GOES archive uses.
                       The picture itself is untouched, pixel for pixel.
  BMP   (.bmp)         saved as a PNG instead and then tagged. BMP holds no
                       metadata at all, and PNG is lossless, so nothing is
                       lost by the change.
  GIF, WEBP            same treatment as BMP.
  TIFF  (.tif .tiff)   NOT tagged. Browsers cannot open TIFF, so the file is
                       copied unchanged and its details go to samples.csv
                       alone. Set the microscope to PNG or JPEG instead.

The page warns you as soon as an untaggable file is loaded, and again after
saving, so nothing goes unnoticed. Every format is recorded in samples.csv
either way, and the exif_written and converted columns say what happened to
each file.

samples.csv columns:

  filename, sample_type, sample_id, provider, location, water_type, date_sampled,
  time_sampled, day_night, latitude, longitude, lat_dm, lon_dm, frame,
  frames_in_sample, original_name, exif_written, converted, saved,
  app_version


GIVING IT TO VOLUNTEERS
-----------------------

Email them the single HTML file, or put it on the GOES website for download.
Once they have the file it keeps working for ever, offline, with no updates
and no installation.


WHAT WAS CHECKED
----------------

The page was driven by an automated browser: 28 checks on the coordinate
reader, the date and time readers and the solar calculation, then the whole
sequence a volunteer performs. Every field was emptied or corrupted in turn
to confirm the Save button switches off each time. A complete sample was then
saved, and the resulting JPEG was opened with an independent library, which
read back the position 13.69 N, 42.38 W, the sample time 09:40 and the UTC
timestamp 11:40, all correct.

The desktop Python version in the folder above does the same job and can be
used instead. This page exists because it needs nothing installed.

GOES Foundation, www.goesfoundation.com
